feat(nfse-key): add isValidNfseKey, parseNfseKey and getNfseKeyInfo - #565

Update (2026-09-27)

• The stack was rebuilt from feat(gtin): add isValidGtin and getGtinInfo #563 up: fix(business-days): stop the day walk from hanging in five time zones, and show the month recipe #561 dropped getNthBusinessDay, getNextBusinessDay and getLastBusinessDayOfMonth (the existing addBusinessDays/subBusinessDays already answer them; see fix(business-days): stop the day walk from hanging in five time zones, and show the month recipe #561), so every branch above it was rebased onto the new history. Each branch's own change set is identical to before apart from those three functions, which was checked line by line.
• isValidNfseKey no longer calls getNfseKeyInfo: it runs the checks itself (format, UF, generator environment, tax ID type and its CPF/CNPJ check digits, number, month, mod11 check digit), and getNfseKeyInfo starts with if (!isValidNfseKey(value)) return null; and only builds the object. The constants moved to src/_internals/constants/nfse-key.ts. Single import: isValidNfseKey 1661 → 1509 B gzip.
• parseNfseKey reads a number only when it is a non-negative safe integer: parseNfseKey(1e21) was "121" and is now "". Strings and non-negative integers are unchanged.
• The national key now accepts an alphanumeric CNPJ (in production since 10/08/2026): letters only in the 14 positions of the inscrição federal when tpInsc is 2, the CNPJ checked with isValidCnpj version 2, and the key DV computed with ASCII − 48 by analogy with NT Conjunta 2025.001 (no NFS-e note states it). The official TSChaveNFSe pattern puts the letter window at positions 7–20, inconsistent with the key structure and with TSIdNFSe (10–23); the library follows the structure and documents the inconsistency. parseNfseKey keeps the letters.

Every branch of the stack was re-validated after the rebuild: npm run check, the full suite with 100% coverage, knip, jscpd (0 clones), check:api and commitlint.

Stacked on #567. This PR sits on top of #567 (obfuscate, obfuscateEmail, obfuscatePixKey) and merges after it, which in turn sits on #573, #561, #563, #562, #560, #559 and #558. Its base branch is claude/obfuscate-more, so the diff shown here is the NFS-e key change alone. Part of stack #591, with #569, #566, #564, #568 and #576 on top of it.

Part of #541 (section 2, access key family). The NBS and LC 116/2003 lookups are in #569 (branch claude/nfse-lookups), since they bring datasets and generator scripts that deserve their own review.

What

Three utilities for the access key (chave de acesso) of the national NFS-e (Sistema Nacional NFS-e): isValidNfseKey, parseNfseKey and getNfseKeyInfo. Every point the issue marked "to confirm" was resolved against the official technical documentation, not from memory; what could not be resolved is left out and listed under Open points.

API

isValidNfseKey(value: string): boolean;
parseNfseKey(value: string | number): string;
getNfseKeyInfo(value: string): NfseKeyInfo | null;

type NfseKeyGeneratorEnvironment = 1 | 2; // ambGer: 1 municipality, 2 Sistema Nacional NFS-e
type NfseKeyTaxIdType = "cpf" | "cnpj";
type NfseKeyInfo = {
	municipalityCode: string; // 7 digit IBGE code
	stateCode: StateCode;
	generatorEnvironment: NfseKeyGeneratorEnvironment;
	taxIdType: NfseKeyTaxIdType;
	taxId: string; // 11 digit CPF (without the 000 padding) or 14 digit CNPJ
	number: number; // nNFSe
	year: number;
	month: number;
	code: string; // 9 digit numeric code
	checkDigit: number;
};

isValidNfseKey("35503082258716523000119000000000001226011357924683"); // true
isValidNfseKey("NFS35503082258716523000119000000000001226011357924683"); // true (XML Id prefix)
isValidNfseKey("3550308 2 2 58716523000119 0000000000012 2601 135792468 3"); // false (the key has no mask)

parseNfseKey("NFS35503082258716523000119000000000001226011357924683");
// "35503082258716523000119000000000001226011357924683"

getNfseKeyInfo("43149021100040364478829000000000105725120484407255");
// { municipalityCode: "4314902", stateCode: "RS", generatorEnvironment: 1, taxIdType: "cpf",
//   taxId: "40364478829", number: 1057, year: 2025, month: 12, code: "048440725", checkDigit: 5 }

Rules applied: 50 digits in one block (optional NFS prefix, surrounding whitespace trimmed), the municipality code starts with an IBGE UF code, ambGer is 1 or 2, the registration type is 1 (CPF left padded with 000) or 2 (CNPJ) and the CPF/CNPJ has valid check digits, nNFSe is not all zeros, the month is 01 to 12, and the DV is the modulus 11 (weights 2 to 9 from the right, remainder 0 or 1 gives 0) over the first 49 digits. It reuses mod11 (variant: "arrecadacao"), IBGE_UF_CODES, isValidCpf and isValidCnpj; the key constants moved to src/_internals/constants/nfse-key.ts, and parseNfseKey now reads NFSE_KEY_LENGTH from there.

Sources

All under https://www.gov.br/nfse/pt-br/biblioteca/documentacao-tecnica (fetched on 2026-09-19):

• NFSe-ESQUEMAS_XSD-v1.01-20260209.zip, tiposSimples_v1.01.xsd: TSIdNFSe documents the layout verbatim, "NFS" + Cód.Mun.(7) + Amb.Ger.(1) + Tipo de Inscrição Federal(1) + Inscrição Federal(14) + No.NFS-e(13) + AnoMes Emis.(4) + Cód.Num.(9) + DV(1), pattern NFS[0-9]{50}; TSChaveNFSe is [0-9]{50}; TSAmbGeradorNFSe is 1 - Prefeitura; 2 - Sistema Nacional da NFS-e; TSNNFSe is [1-9]{1}[0-9]{0,12}.
• ANEXO_I-SEFIN_ADN-DPS_NFSe-SNNFSe-v1.01-20260209.xlsx: field NFSe/infNFSe/id repeats the layout ("Inscrição Federal (14 - CPF completar com 000 à esquerda)"); rule E1263 states "Tipo de inscrição Federal = 1 / CPF", "= 2 / CNPJ"; rules E1280/E1284 reject an issuer CNPJ/CPF with a wrong DV; rules E0042, E0455 and E0907 say "Verificar DV da chave".
• Manual de Contribuintes, Emissão por Decisão Administrativa ou Judicial (manual-contribuintes-emissor-publico-api-emissao-decisao-administrativa-e-judicial.pdf), field id: "O dígito verificador deve ser calculado segundo o algoritmo do módulo 11". It is the only official sentence on the DV algorithm I found.
• Nota Técnica SE/CGNFS-e 008 v1.02 (DANFSe), item 2.1.1: "A chave de acesso será impressa em único bloco contendo 50 dígitos", hence no mask is accepted and there is no formatter.
• Nota Técnica SE/CGNFS-e 009 v1.0 (item 2.1, CNPJ alfanumérico) and the schema package of the restricted production environment (esquemas-nfse-rtc-v1-01-20260727.zip): see Open points.

The weights and the remainder rule are not spelled out by any official NFS-e document. They were confirmed empirically: a throwaway script collected the NFS-e keys found in public GitHub repositories (fixtures of nfse-nacional/nfse-php, Unimake/DFe, akretion/nfelib and others) and 115 of them, generated by both environments (ambGer 1 and 2) and covering remainders 0, 1 and 10, match the DF-e modulus 11. No other hypothesis comes close: the other remainder mapping (variant: "boleto") matches clearly fewer keys, and a modulus 11 over the 9 digit Cód.Num. alone matches almost none. The keys that do not match are sample XMLs whose DV was filled in by hand, many of them built around the standard fake CNPJs 00000000000191, 12345678000195 and 11222333000181; a few are otherwise well formed vendor samples with a valid issuer CNPJ, such as 33045572214043710000103000000000001826012751532719 (DV 9, the rule gives 1) and 43100091276077080000145000000000001426012205619530 (DV 0, the rule gives 3). So the sample is not unanimous, only decisive. None of those keys is in the test suite: every key in the tests is synthetic, built by hand from the algorithm around the CNPJ/CPF test values the repository already uses.

Verification

• npm run check: pass.
• npm run test -- --run: 187 files, 6213 passed.
• npm run test:coverage: 100% statements, branches, functions and lines.
• npm run build (attw and publint clean), npm run check:api:update (report committed), npm run check:unused, npm run check:duplication (0 clones), npm run check:commits: pass.
• npm run check:tree-shaking: pass; isValidNfseKey 3230 B (1509 B gzip), getNfseKeyInfo 3208 B (1652 B gzip), parseNfseKey 1003 B (621 B gzip). No dataset involved, so the bundle-size tables are unchanged.
• npm run test:mutation -- --mutate on the three new files: 100% (75 mutants, none surviving, no Stryker disable comments).
• npm run test:bun and npm run test:deno: pass.
• Not run, per the shared-machine instructions: browser test scripts and the full Stryker run.
• npm run build:llms and npm run build:site were run; only the llms files changed.

Open points

• No formatNfseKey. The issue proposed one, but the only official printed form is the single block of 50 digits (NT 008, item 2.1.1), which is what parseNfseKey already returns. Any grouping would be a convention of this library, so it is left out; easy to add if the maintainers want a field-grouped display form.
• Alphanumeric CNPJ. Now supported (see the Update above). The DV rule for letters (ASCII − 48) is taken by analogy with NT Conjunta 2025.001, since no NFS-e document states it.
• The DV variant rests on one official sentence ("algoritmo do módulo 11") plus the empirical confirmation above, not on a published worked example.
• What the DV covers. The Guia do Emissor Público Nacional Web (v1.2 section 9.1 and v1.2.1) closes its field list with "Dígito Verificador: Dígito verificador do código numérico", which read literally would put the DV over the 9 digit Cód.Num. alone. That reading matches almost none of the real keys collected above, while the DV over the first 49 digits matches nearly all of them, so it is taken as loose wording. It is the only official sentence that says anything about what the DV covers.
• The example key printed in the Guia do Emissor Público Nacional Web v1.2, item 9.1 (31062001251235800000112230000000173023019580208160), does not pass the modulus 11, and its "Inscrição Federal" 51235800000112 is not a valid CNPJ either (the first check digit should be 2), so it is an illustrative value. v1.2.1 also replaces the "44 dígitos" of v1.2 with "50 caracteres" while keeping the same example. The test suite pins it as invalid with that note.
• Keys with nNFSe = 0. 14001591201761135000132000000000000022096100197260 and 14001591201761135000132000000000000022097781063609 appear as <chNFSe> in public NACIONAL 1.01 sample XMLs; both decompose cleanly and their DV matches the rule, but their nNFSe is all zeros, so this package rejects them. TSNNFSe is [1-9]{1}[0-9]{0,12}, rule E1263 ties the key to those fields and getNfeKeyInfo applies the same rule to the DF-e key, so the rejection is kept; no official text says whether a production key may carry a zero nNFSe.
• The municipality code is checked only for its UF prefix. Looking it up would pull the municipalities dataset into every consumer of the validator.
• Event identifiers (EVT/PRE + key + event type + sequence) and the 42 digit DPS identifier are out of scope.

Summary by CodeRabbit

• New Features

  • Added support for parsing, validating, and extracting information from national NFS-e access keys.
  • Supports optional NFS prefixes, formatted inputs, CPF/CNPJ data, dates, invoice numbers, and check digits.
  • Added structured key information and related TypeScript types to the public API.
  • Added package entry points for the new NFS-e utilities.

• Documentation

  • Added English and Portuguese documentation with supported formats, constraints, and examples.